<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title>Hoodoo::Utilities</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <link rel="stylesheet" href="../../css/reset.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/main.css" type="text/css" media="screen" />
<link rel="stylesheet" href="../../css/github.css" type="text/css" media="screen" />
<script src="../../js/jquery-1.3.2.min.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/jquery-effect.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/main.js" type="text/javascript" charset="utf-8"></script>
<script src="../../js/highlight.pack.js" type="text/javascript" charset="utf-8"></script>

</head>

<body>
    <div class="banner">
        <h1>
            <span class="type">Module</span>
            Hoodoo::Utilities
        </h1>
        <ul class="files">
            <li><a href="../../files/lib/hoodoo/utilities/utilities_rb.html">lib/hoodoo/utilities/utilities.rb</a></li>
        </ul>
    </div>
    <div id="bodyContent">
        <div id="content">
    <div class="description">
      
<p>Useful tools, especially for those working without Rails components.</p>

    </div>








    <!-- Method ref -->
    <div class="sectiontitle">Methods</div>
    <dl class="methods">
        <dt>C</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-collated_hash_from">collated_hash_from</a>
              </li>
          </ul>
        </dd>
        <dt>D</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-deep_dup">deep_dup</a>,
              </li>
              <li>
                <a href="#method-c-deep_merge_into">deep_merge_into</a>
              </li>
          </ul>
        </dd>
        <dt>H</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-hash_diff">hash_diff</a>,
              </li>
              <li>
                <a href="#method-c-hash_key_paths">hash_key_paths</a>
              </li>
          </ul>
        </dd>
        <dt>N</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-nanosecond_iso8601">nanosecond_iso8601</a>
              </li>
          </ul>
        </dd>
        <dt>R</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-rationalise_datetime">rationalise_datetime</a>
              </li>
          </ul>
        </dd>
        <dt>S</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-spare_port">spare_port</a>,
              </li>
              <li>
                <a href="#method-c-stringify">stringify</a>,
              </li>
              <li>
                <a href="#method-c-symbolize">symbolize</a>
              </li>
          </ul>
        </dd>
        <dt>T</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-to_integer-3F">to_integer?</a>
              </li>
          </ul>
        </dd>
        <dt>V</dt>
        <dd>
          <ul>
              <li>
                <a href="#method-c-valid_iso8601_subset_date-3F">valid_iso8601_subset_date?</a>,
              </li>
              <li>
                <a href="#method-c-valid_iso8601_subset_datetime-3F">valid_iso8601_subset_datetime?</a>
              </li>
          </ul>
        </dd>
    </dl>







      <!-- Section constants -->
      <div class="sectiontitle">Constants</div>
      <table border='0' cellpadding='5'>
          <tr valign='top' id='DATETIME_ISO8601_SUBSET_REGEXP'>
            <td class="attr-name">DATETIME_ISO8601_SUBSET_REGEXP</td>
            <td>=</td>
            <td class="attr-value"><pre>/(\d{4})-(\d{2})-(\d{2})T(\d{2})\:(\d{2})\:(\d{2})(\.\d+)?(Z|[+-](\d{2})\:(\d{2}))/</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Validation regular expression for DateTime subset selection.</p></td>
            </tr>
          <tr valign='top' id='DATE_ISO8601_SUBSET_REGEXP'>
            <td class="attr-name">DATE_ISO8601_SUBSET_REGEXP</td>
            <td>=</td>
            <td class="attr-value"><pre>/(\d{4})-(\d{2})-(\d{2})/</pre></td>
          </tr>
            <tr valign='top'>
              <td>&nbsp;</td>
              <td colspan="2" class="attr-desc"><p>Validation regular expression for Date subset selection.</p></td>
            </tr>
      </table>



    <!-- Methods -->
      <div class="sectiontitle">Class Public methods</div>
        <div class="method">
          <div class="title method-title" id="method-c-collated_hash_from">
              <b>collated_hash_from</b>( array, dupes = false )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-collated_hash_from" name="method-c-collated_hash_from" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>A very single-purpose method which converts an Array of specifc form into a
Hash.</p>

<p>The Hash class can already build itself from an Array of tuples, thus:</p>

<pre><code>array = [ [ :one, 1 ], [ :two, 2 ] ]
hash  = Hash[ array ]
# =&gt; { :one =&gt; 1, :two =&gt; 2 }
</code></pre>

<p>This is fine, but what if the array contains the same key twice?</p>

<pre><code>array = [ [ :one, 1 ], [ :two, 2 ], [ :one, 42 ] ]
hash  = Hash[ array ]
# =&gt; { :one =&gt; 42, :two =&gt; 2 }
</code></pre>

<p>The later duplicates simply override any former entries. This Array
collation method is designed to instead take the tuples and set up a Hash
where each key leads to an Array of unique values found in the original,
thus:</p>

<pre><code>array = [ [ :one, 1 ], [ :two, 2 ], [ :one, 42 ] ]
Hoodoo::Utilities.collated_hash_from( array )
# =&gt; { :one =&gt; [ 1, 42 ], :two =&gt; [ 2 ] }
</code></pre>

<p>Note that:</p>
<ul><li>
<p>The Hash values are always Arrays, even if they only have one value.</p>
</li><li>
<p>The Array values are unique; duplicates are removed via <code>uniq!</code>.</p>
</li></ul>
<dl class="rdoc-list note-list"><dt><code>array</code>
<dd>
<p>Array of two-element Arrays. The first element becomes a key in the
returned Hash. The last element is added to an Array of (unique) values
associated with that key. An empty Array results in an empty Hash;
<code>nil</code> is not allowed.</p>
</dd><dt><code>dupes</code>
<dd>
<p>Optional. If omitted, duplicates are removed as described; if present and
<code>true</code>, duplicates are allowed.</p>
</dd></dl>

<p>Returns a new Hash as described. The input Array is not modified.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-collated_hash_from_source')" id="l_method-c-collated_hash_from_source">show</a>
              </p>
              <div id="method-c-collated_hash_from_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 252</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">collated_hash_from</span>( <span class="ruby-identifier">array</span>, <span class="ruby-identifier">dupes</span> = <span class="ruby-keyword">false</span> )
  <span class="ruby-identifier">hash_of_arrays</span> = {}

  <span class="ruby-identifier">array</span>.<span class="ruby-identifier">reduce</span>( <span class="ruby-identifier">hash_of_arrays</span> ) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>, <span class="ruby-identifier">sub_array</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">memo</span>[ <span class="ruby-identifier">sub_array</span>.<span class="ruby-identifier">first</span> ] = ( <span class="ruby-identifier">memo</span>[ <span class="ruby-identifier">sub_array</span>.<span class="ruby-identifier">first</span> ] <span class="ruby-operator">||</span> [] ) <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-identifier">sub_array</span>.<span class="ruby-identifier">last</span>
    <span class="ruby-identifier">memo</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-identifier">hash_of_arrays</span>.<span class="ruby-identifier">values</span>.<span class="ruby-identifier">collect</span>( <span class="ruby-operator">&amp;</span><span class="ruby-value">:uniq!</span> ) <span class="ruby-keyword">unless</span> <span class="ruby-identifier">dupes</span> <span class="ruby-operator">==</span> <span class="ruby-keyword">true</span>
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">hash_of_arrays</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-deep_dup">
              <b>deep_dup</b>( obj )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-deep_dup" name="method-c-deep_dup" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Thorough but slow deep duplication of any object (if it isn&#39;t
duplicable, e.g. FixNum, you just get the same thing back). Usually used
with Hashes or Arrays.</p>
<dl class="rdoc-list note-list"><dt><code>obj</code>
<dd>
<p>Object to duplicate.</p>
</dd></dl>

<p>Returns the duplicated object if duplicable, else returns the input
parameter.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-deep_dup_source')" id="l_method-c-deep_dup_source">show</a>
              </p>
              <div id="method-c-deep_dup_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 69</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">deep_dup</span>( <span class="ruby-identifier">obj</span> )
  <span class="ruby-identifier">duplicate</span> = <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">dup</span> <span class="ruby-keyword">rescue</span> <span class="ruby-identifier">obj</span>

  <span class="ruby-identifier">result</span> = <span class="ruby-keyword">if</span> <span class="ruby-identifier">duplicate</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hash</span> )
    <span class="ruby-identifier">duplicate</span>.<span class="ruby-identifier">each</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">k</span>, <span class="ruby-identifier">v</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">duplicate</span>[ <span class="ruby-identifier">k</span> ] = <span class="ruby-identifier">deep_dup</span>( <span class="ruby-identifier">v</span> ) }
  <span class="ruby-keyword">elsif</span> <span class="ruby-identifier">duplicate</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Array</span> )
    <span class="ruby-identifier">duplicate</span>.<span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">entry</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">deep_dup</span>( <span class="ruby-identifier">entry</span> ) }
  <span class="ruby-keyword">else</span>
    <span class="ruby-identifier">duplicate</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">result</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-deep_merge_into">
              <b>deep_merge_into</b>( target_hash, inbound_hash )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-deep_merge_into" name="method-c-deep_merge_into" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deep merge two hashes.</p>

<p>Hash#merge/merge! only do a shallow merge. For example, without a block,
when starting with this hash:</p>

<pre><code>{ :one =&gt; { :two =&gt; { :three =&gt; 3 } } }
</code></pre>

<p>…and merging in this hash:</p>

<pre><code>{ :one =&gt; { :two =&gt; { :and_four =&gt; 4 } } }
</code></pre>

<p>…the possibly unexpected result is this:</p>

<pre><code>{ :one =&gt; { :two =&gt; { :and_four =&gt; 4 } } }
</code></pre>

<p>Because the value for key “:one” in the original hash is simply overwritten
with the value from the merged-in hash.</p>

<p>Deep merging takes a target hash, into which an “inbound” source hash is
merged and returns a new hash that is the deep merged result. Taking the
above example:</p>

<pre><code>target_hash  = { :one =&gt; { :two =&gt; { :three =&gt; 3 } } }
inbound_hash = { :one =&gt; { :two =&gt; { :and_four =&gt; 4 } } }
Hoodoo::Utilities.deep_merge_into( target_hash, inbound_hash )
</code></pre>

<p>…yields:</p>

<pre><code>{ :one =&gt; { :two =&gt; { :three =&gt; 3, :and_four =&gt; 4 } } }
</code></pre>

<p>For any same-named key with a non-hash value, the value in the inbound hash
will overwrite the value in the target hash.</p>

<p>Parameters:</p>
<dl class="rdoc-list note-list"><dt><code>target_hash</code>
<dd>
<p>The hash into which something will be merged.</p>
</dd><dt><code>inbound_hash</code>
<dd>
<p>The hash that will be merged into the target.</p>
</dd></dl>

<p>Returns the merged result.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-deep_merge_into_source')" id="l_method-c-deep_merge_into_source">show</a>
              </p>
              <div id="method-c-deep_merge_into_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 123</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">deep_merge_into</span>( <span class="ruby-identifier">target_hash</span>, <span class="ruby-identifier">inbound_hash</span> )

  <span class="ruby-comment"># http://stackoverflow.com/questions/9381553/ruby-merge-nested-hash</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-identifier">merger</span> = <span class="ruby-identifier">proc</span> { <span class="ruby-operator">|</span> <span class="ruby-identifier">key</span>, <span class="ruby-identifier">v1</span>, <span class="ruby-identifier">v2</span> <span class="ruby-operator">|</span>
    <span class="ruby-identifier">v1</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hash</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">v2</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hash</span> ) <span class="ruby-operator">?</span> <span class="ruby-identifier">v1</span>.<span class="ruby-identifier">merge</span>( <span class="ruby-identifier">v2</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">merger</span> ) <span class="ruby-operator">:</span> <span class="ruby-identifier">v2</span>.<span class="ruby-identifier">nil?</span> <span class="ruby-operator">?</span> <span class="ruby-identifier">v1</span> <span class="ruby-operator">:</span> <span class="ruby-identifier">v2</span>
  }

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">target_hash</span>.<span class="ruby-identifier">merge</span>( <span class="ruby-identifier">inbound_hash</span>, <span class="ruby-operator">&amp;</span><span class="ruby-identifier">merger</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-hash_diff">
              <b>hash_diff</b>( hash1, hash2 )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-hash_diff" name="method-c-hash_diff" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Deep diff two hashes.</p>
<dl class="rdoc-list note-list"><dt>hash1
<dd>
<p>“Left hand” hash for comparison.</p>
</dd><dt>hash2
<dd>
<p>“Right hand” hash for comparison.</p>
</dd></dl>

<p>The returned result is a Hash itself, potentially nested, with any present
key paths leading to an array describing the difference found at that key
path. If the two input hashes had values at the path, the differing values
are placed in the array (“left hand” value at index 0, “right hand” at
index 1). If one input hash has a key leading to a value which the other
omits, the array contains <code>nil</code> for the omitted entry.</p>

<p>Example:</p>

<pre><code>hash1 = { :foo =&gt; { :bar =&gt; 2 }, :baz =&gt; true, :boo =&gt; false }
hash2 = { :foo =&gt; { :bar =&gt; 3 },               :boo =&gt; false }

Hoodoo::Utilities.hash_diff( hash1, hash2 )
# =&gt; { :foo =&gt; { :bar =&gt; [ 2, 3 ] }, :baz =&gt; [ true, nil ] }

Hoodoo::Utilities.hash_diff( hash2, hash1 )
# =&gt; { :foo =&gt; { :bar =&gt; [ 3, 2 ] }, :baz =&gt; [ nil, true ] }
</code></pre>

<p>Bear in mind that the difference array contains values of everything
different from the first part of the key path where things diverge. So in
this case:</p>

<pre><code>hash1 = { :foo =&gt; { :bar =&gt; { :baz =&gt; [ 1, 2, 3 ] } } }
hash2 = {}
</code></pre>

<p>…the difference starts all the way up at “:foo”. The result is thus
<strong>not</strong> a Hash where just the “:baz” array is picked out as a
difference; the entire Hash sub-tree is picked out:</p>

<pre><code>diff = Hoodoo::Utilities.hash_diff( hash1, hash2 )
# =&gt; { :foo =&gt; [ { :bar =&gt; { :baz =&gt; [ 1, 2, 3 ] } }, nil ] }
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-hash_diff_source')" id="l_method-c-hash_diff_source">show</a>
              </p>
              <div id="method-c-hash_diff_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 172</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">hash_diff</span>( <span class="ruby-identifier">hash1</span>, <span class="ruby-identifier">hash2</span> )

  <span class="ruby-comment"># http://stackoverflow.com/questions/1766741/comparing-ruby-hashes</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-keyword">return</span> ( <span class="ruby-identifier">hash1</span>.<span class="ruby-identifier">keys</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">hash2</span>.<span class="ruby-identifier">keys</span> ).<span class="ruby-identifier">inject</span>( {} ) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>, <span class="ruby-identifier">key</span> <span class="ruby-operator">|</span>
    <span class="ruby-keyword">unless</span> <span class="ruby-identifier">hash1</span>[ <span class="ruby-identifier">key</span> ] <span class="ruby-operator">==</span> <span class="ruby-identifier">hash2</span>[ <span class="ruby-identifier">key</span> ]
      <span class="ruby-keyword">if</span> <span class="ruby-identifier">hash1</span>[ <span class="ruby-identifier">key</span> ].<span class="ruby-identifier">kind_of?</span>( <span class="ruby-constant">Hash</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">hash2</span>[ <span class="ruby-identifier">key</span> ].<span class="ruby-identifier">kind_of?</span>( <span class="ruby-constant">Hash</span> )
        <span class="ruby-identifier">memo</span>[ <span class="ruby-identifier">key</span> ] = <span class="ruby-identifier">hash_diff</span>( <span class="ruby-identifier">hash1</span>[ <span class="ruby-identifier">key</span> ], <span class="ruby-identifier">hash2</span>[ <span class="ruby-identifier">key</span> ] )
      <span class="ruby-keyword">else</span>
        <span class="ruby-identifier">memo</span>[ <span class="ruby-identifier">key</span> ] = [ <span class="ruby-identifier">hash1</span>[ <span class="ruby-identifier">key</span> ], <span class="ruby-identifier">hash2</span>[ <span class="ruby-identifier">key</span> ] ]
      <span class="ruby-keyword">end</span>
    <span class="ruby-keyword">end</span>

    <span class="ruby-identifier">memo</span>
  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-hash_key_paths">
              <b>hash_key_paths</b>( hash )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-hash_key_paths" name="method-c-hash_key_paths" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Convert a (potentially nested) Hash into an array of entries which
represent its keys, with the notation “foo.bar.baz” for nested hashes.</p>
<dl class="rdoc-list note-list"><dt><code>hash</code>
<dd>
<p>Input Hash.</p>
</dd></dl>

<p>Example:</p>

<pre><code>hash = { :foo =&gt; 1, :bar =&gt; { :baz =&gt; 2, :boo =&gt; { :hello =&gt; :world } } }

Hoodoo::Utilities.hash_key_paths( hash )
# =&gt; [ &#39;foo&#39;, &#39;bar.baz&#39;, &#39;bar.boo.hello&#39; ]
</code></pre>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-hash_key_paths_source')" id="l_method-c-hash_key_paths_source">show</a>
              </p>
              <div id="method-c-hash_key_paths_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 201</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">hash_key_paths</span>( <span class="ruby-identifier">hash</span> )
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">hash</span>.<span class="ruby-identifier">map</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">key</span>, <span class="ruby-identifier">value</span> <span class="ruby-operator">|</span>
    <span class="ruby-keyword">if</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Hash</span> )
      <span class="ruby-identifier">hash_key_paths</span>( <span class="ruby-identifier">value</span> ).<span class="ruby-identifier">map</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span> <span class="ruby-identifier">entry</span> <span class="ruby-operator">|</span>
        <span class="ruby-node">&quot;#{ key }.#{ entry }&quot;</span>
      <span class="ruby-keyword">end</span>
    <span class="ruby-keyword">else</span>
      <span class="ruby-identifier">key</span>.<span class="ruby-identifier">to_s</span>
    <span class="ruby-keyword">end</span>
  <span class="ruby-keyword">end</span>.<span class="ruby-identifier">flatten</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-nanosecond_iso8601">
              <b>nanosecond_iso8601</b>( time_or_date_time )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-nanosecond_iso8601" name="method-c-nanosecond_iso8601" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Returns an ISO 8601 String equivalent of the given Time or DateTime
instance, with nanosecond precision (subject to Ruby port / OS support).
This is nothing more than a standardised central interface on calling
Ruby&#39;s <code>Time/DateTime#iso8601( 9 )</code>, to avoid the risk of
lots of variable length precision times floating around by authors picking
their own arbitrary precision parameters.</p>
<dl class="rdoc-list note-list"><dt><code>date_time</code>
<dd>
<p>Ruby Time or DateTime instance to convert to an ISO 8601 String with
nanosecond precision.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-nanosecond_iso8601_source')" id="l_method-c-nanosecond_iso8601_source">show</a>
              </p>
              <div id="method-c-nanosecond_iso8601_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 351</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">nanosecond_iso8601</span>( <span class="ruby-identifier">time_or_date_time</span> )
  <span class="ruby-identifier">time_or_date_time</span>.<span class="ruby-identifier">iso8601</span>( <span class="ruby-number">9</span> )
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-rationalise_datetime">
              <b>rationalise_datetime</b>( input )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-rationalise_datetime" name="method-c-rationalise_datetime" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Turn a given value of various types into a DateTime instance or
<code>nil</code>. If the input value is not <code>nil</code>, a DateTime
instance, a Time instance or something that <code>DateTime.parse</code> can
handle, the method will throw a RuntimeError exception.</p>
<dl class="rdoc-list note-list"><dt><code>input</code>
<dd>
<p>A Time or DateTime instance, or a String that can be converted to a
DateTime instance; in these cases, an equivalent DateTime is returned. If
<code>nil</code>, returns <code>nil</code>.</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-rationalise_datetime_source')" id="l_method-c-rationalise_datetime_source">show</a>
              </p>
              <div id="method-c-rationalise_datetime_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 364</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">rationalise_datetime</span>( <span class="ruby-identifier">input</span> )
  <span class="ruby-keyword">begin</span>
    <span class="ruby-keyword">if</span> <span class="ruby-identifier">input</span>.<span class="ruby-identifier">nil?</span> <span class="ruby-operator">||</span> <span class="ruby-identifier">input</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">DateTime</span> )
      <span class="ruby-identifier">input</span>
    <span class="ruby-keyword">elsif</span> <span class="ruby-identifier">input</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-constant">Time</span> )
      <span class="ruby-identifier">input</span>.<span class="ruby-identifier">to_datetime</span>
    <span class="ruby-keyword">else</span>
      <span class="ruby-constant">DateTime</span>.<span class="ruby-identifier">parse</span>( <span class="ruby-identifier">input</span> )
    <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">rescue</span>
    <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Hoodoo::Utilities\#rationalise_datetime: Invalid parameter &#39;#{ input }&#39;&quot;</span>

  <span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-spare_port">
              <b>spare_port</b>()
            <a href="../../classes/Hoodoo/Utilities.html#method-c-spare_port" name="method-c-spare_port" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Return a spare TCP port on localhost. This is free at the instant of
calling, though of course if you have anything in other local machine
processes/threads running which might start using ports at any moment,
there&#39;s a chance of the free port getting claimed in between you asking
for it and it being returned. This utility method is usually therefore used
for test environments only.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-spare_port_source')" id="l_method-c-spare_port_source">show</a>
              </p>
              <div id="method-c-spare_port_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 282</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">spare_port</span>

  <span class="ruby-comment"># http://stackoverflow.com/questions/5985822/how-do-you-find-a-random-open-port-in-ruby</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-identifier">socket</span> = <span class="ruby-constant">Socket</span>.<span class="ruby-identifier">new</span>( <span class="ruby-value">:INET</span>, <span class="ruby-value">:STREAM</span>, <span class="ruby-number">0</span> )
  <span class="ruby-identifier">socket</span>.<span class="ruby-identifier">bind</span>( <span class="ruby-constant">Addrinfo</span>.<span class="ruby-identifier">tcp</span>( <span class="ruby-string">&#39;127.0.0.1&#39;</span>, <span class="ruby-number">0</span> ) )
  <span class="ruby-identifier">port</span> = <span class="ruby-identifier">socket</span>.<span class="ruby-identifier">local_address</span>.<span class="ruby-identifier">ip_port</span>
  <span class="ruby-identifier">socket</span>.<span class="ruby-identifier">close</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">port</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-stringify">
              <b>stringify</b>(obj)
            <a href="../../classes/Hoodoo/Utilities.html#method-c-stringify" name="method-c-stringify" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>The keys-to-strings equivalent of <a
href="Utilities.html#method-c-symbolize">::symbolize</a>.</p>
<dl class="rdoc-list note-list"><dt>obj
<dd>
<p>Hash or Array of Hashes. Will recursively convert keys in Hashes to
strings. Hashes with values that are Arrays of Hashes will be dealt with
properly. Does not modify other types (e.g. an Array of Symbols would stay
an Array of Symbols).</p>
</dd></dl>

<p>Returns a copy of your input object with keys converted to strings.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-stringify_source')" id="l_method-c-stringify_source">show</a>
              </p>
              <div id="method-c-stringify_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 54</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">stringify</span>(<span class="ruby-identifier">obj</span>)
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">inject</span>({}){<span class="ruby-operator">|</span><span class="ruby-identifier">memo</span>,(<span class="ruby-identifier">k</span>,<span class="ruby-identifier">v</span>)<span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>[<span class="ruby-identifier">k</span>.<span class="ruby-identifier">to_s</span>] =  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">stringify</span>(<span class="ruby-identifier">v</span>); <span class="ruby-identifier">memo</span>} <span class="ruby-keyword">if</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-operator">::</span><span class="ruby-constant">Hash</span>)
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">inject</span>([]){<span class="ruby-operator">|</span><span class="ruby-identifier">memo</span>,<span class="ruby-identifier">v</span>    <span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>         <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">stringify</span>(<span class="ruby-identifier">v</span>); <span class="ruby-identifier">memo</span>} <span class="ruby-keyword">if</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-operator">::</span><span class="ruby-constant">Array</span>)
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-symbolize">
              <b>symbolize</b>(obj)
            <a href="../../classes/Hoodoo/Utilities.html#method-c-symbolize" name="method-c-symbolize" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Given a hash, returns the same hash with keys converted to symbols. Works
with nested hashes.</p>
<dl class="rdoc-list note-list"><dt>obj
<dd>
<p>Hash or Array of Hashes. Will recursively convert keys in Hashes to
symbols. Hashes with values that are Arrays of Hashes will be dealt with
properly. Does not modify other types (e.g. an Array of Strings would stay
an Array of Strings).</p>
</dd></dl>

<p>Returns a copy of your input object with keys converted to symbols.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-symbolize_source')" id="l_method-c-symbolize_source">show</a>
              </p>
              <div id="method-c-symbolize_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 36</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">symbolize</span>(<span class="ruby-identifier">obj</span>)

  <span class="ruby-comment"># http://stackoverflow.com/questions/800122/best-way-to-convert-strings-to-symbols-in-hash</span>
  <span class="ruby-comment">#</span>
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">inject</span>({}){<span class="ruby-operator">|</span><span class="ruby-identifier">memo</span>,(<span class="ruby-identifier">k</span>,<span class="ruby-identifier">v</span>)<span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>[<span class="ruby-identifier">k</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">to_sym</span>] =  <span class="ruby-keyword">self</span>.<span class="ruby-identifier">symbolize</span>(<span class="ruby-identifier">v</span>); <span class="ruby-identifier">memo</span>} <span class="ruby-keyword">if</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-operator">::</span><span class="ruby-constant">Hash</span>)
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">inject</span>([]){<span class="ruby-operator">|</span><span class="ruby-identifier">memo</span>,<span class="ruby-identifier">v</span>    <span class="ruby-operator">|</span> <span class="ruby-identifier">memo</span>                <span class="ruby-operator">&lt;&lt;</span> <span class="ruby-keyword">self</span>.<span class="ruby-identifier">symbolize</span>(<span class="ruby-identifier">v</span>); <span class="ruby-identifier">memo</span>} <span class="ruby-keyword">if</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-operator">::</span><span class="ruby-constant">Array</span>)
  <span class="ruby-keyword">return</span> <span class="ruby-identifier">obj</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-to_integer-3F">
              <b>to_integer?</b>( value )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-to_integer-3F" name="method-c-to_integer-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Is a parameter convertable to an integer cleanly? Returns the integer value
if so, else <code>nil</code>.</p>
<dl class="rdoc-list note-list"><dt>value
<dd>
<p>Value to check, e.g. 2, “44”, :&#39;55&#39; (yields 2, 44, 55) or “hello”,
Time.now (yields nil, nil).</p>
</dd></dl>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-to_integer-3F_source')" id="l_method-c-to_integer-3F_source">show</a>
              </p>
              <div id="method-c-to_integer-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 270</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">to_integer?</span>( <span class="ruby-identifier">value</span> )
  <span class="ruby-identifier">value</span> = <span class="ruby-identifier">value</span>.<span class="ruby-identifier">to_s</span>
  <span class="ruby-identifier">value</span>.<span class="ruby-identifier">to_i</span> <span class="ruby-keyword">if</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">to_i</span>.<span class="ruby-identifier">to_s</span> <span class="ruby-operator">==</span> <span class="ruby-identifier">value</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-valid_iso8601_subset_date-3F">
              <b>valid_iso8601_subset_date?</b>( str )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-valid_iso8601_subset_date-3F" name="method-c-valid_iso8601_subset_date-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Is the given String a valid ISO 8601 subset date (no time) as accepted by
(for example) <a href="../Hoodoo.html">Hoodoo</a> API calls?</p>
<dl class="rdoc-list note-list"><dt><code>str</code>
<dd>
<p>Value to check</p>
</dd></dl>

<p>Returns a Date instance holding the parsed result if a valid ISO 8601
subset date, else <code>false</code>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-valid_iso8601_subset_date-3F_source')" id="l_method-c-valid_iso8601_subset_date-3F_source">show</a>
              </p>
              <div id="method-c-valid_iso8601_subset_date-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 326</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">valid_iso8601_subset_date?</span>( <span class="ruby-identifier">str</span> )

  <span class="ruby-comment"># Same reliance as &#39;valid_iso8601_subset_datetime&#39;?.</span>

  <span class="ruby-identifier">value</span> = <span class="ruby-keyword">begin</span>
    ( <span class="ruby-constant">DATE_ISO8601_SUBSET_REGEXP</span> <span class="ruby-operator">=~</span> <span class="ruby-identifier">str</span>.<span class="ruby-identifier">to_s</span> ) <span class="ruby-operator">==</span> <span class="ruby-number">0</span> <span class="ruby-operator">&amp;&amp;</span>
    <span class="ruby-identifier">str</span>.<span class="ruby-identifier">size</span> <span class="ruby-operator">==</span> <span class="ruby-number">10</span>                                  <span class="ruby-operator">&amp;&amp;</span>
    <span class="ruby-operator">::</span><span class="ruby-constant">Date</span>.<span class="ruby-identifier">parse</span>( <span class="ruby-identifier">str</span> )

  <span class="ruby-keyword">rescue</span> <span class="ruby-constant">ArgumentError</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-operator">::</span><span class="ruby-constant">Date</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">value</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
        <div class="method">
          <div class="title method-title" id="method-c-valid_iso8601_subset_datetime-3F">
              <b>valid_iso8601_subset_datetime?</b>( str )
            <a href="../../classes/Hoodoo/Utilities.html#method-c-valid_iso8601_subset_datetime-3F" name="method-c-valid_iso8601_subset_datetime-3F" class="permalink">Link</a>
          </div>

            <div class="description">
              <p>Is the given String a valid ISO 8601 subset date and time as accepted by
(for example) <a href="../Hoodoo.html">Hoodoo</a> API calls?</p>
<dl class="rdoc-list note-list"><dt><code>str</code>
<dd>
<p>Value to check</p>
</dd></dl>

<p>Returns a DateTime instance holding the parsed result if a valid ISO 8601
subset date and time, else <code>false</code>.</p>
            </div>



            <div class="sourcecode">
              <p class="source-link">
                Source:
                <a href="javascript:toggleSource('method-c-valid_iso8601_subset_datetime-3F_source')" id="l_method-c-valid_iso8601_subset_datetime-3F_source">show</a>
              </p>
              <div id="method-c-valid_iso8601_subset_datetime-3F_source" class="dyn-source">
                <pre><span class="ruby-comment"># File lib/hoodoo/utilities/utilities.rb, line 302</span>
<span class="ruby-keyword">def</span> <span class="ruby-keyword ruby-title">self</span>.<span class="ruby-identifier">valid_iso8601_subset_datetime?</span>( <span class="ruby-identifier">str</span> )

  <span class="ruby-comment"># Relies on Ruby evaluation behaviour and operator precedence - &quot;&#39;foo&#39;</span>
  <span class="ruby-comment"># &amp;&amp; true&quot; =&gt; true, but &quot;true &amp;&amp; &#39;foo&#39;&quot; =&gt; &#39;foo&#39;. Don&#39;t use &quot;and&quot; here!</span>

  <span class="ruby-identifier">value</span> = <span class="ruby-keyword">begin</span>
    ( <span class="ruby-constant">DATETIME_ISO8601_SUBSET_REGEXP</span> <span class="ruby-operator">=~</span> <span class="ruby-identifier">str</span>.<span class="ruby-identifier">to_s</span> ) <span class="ruby-operator">==</span> <span class="ruby-number">0</span> <span class="ruby-operator">&amp;&amp;</span>
    <span class="ruby-identifier">str</span>.<span class="ruby-identifier">size</span> <span class="ruby-operator">&gt;</span> <span class="ruby-number">10</span>                                       <span class="ruby-operator">&amp;&amp;</span>
    <span class="ruby-operator">::</span><span class="ruby-constant">DateTime</span>.<span class="ruby-identifier">parse</span>( <span class="ruby-identifier">str</span> )

  <span class="ruby-keyword">rescue</span> <span class="ruby-constant">ArgumentError</span>
  <span class="ruby-keyword">end</span>

  <span class="ruby-keyword">return</span> <span class="ruby-identifier">value</span>.<span class="ruby-identifier">is_a?</span>( <span class="ruby-operator">::</span><span class="ruby-constant">DateTime</span> ) <span class="ruby-operator">&amp;&amp;</span> <span class="ruby-identifier">value</span>
<span class="ruby-keyword">end</span></pre>
              </div>
            </div>
          </div>
</div>

    </div>
  </body>
</html>
